CloudyWing's Note

English

繁體中文

English

繁體中文

Theme

Original note

A Brief Introduction to Git Commit Conventions ​

TLDR ​

  • Git commits should follow the Angular Commit Format, which consists of a Header (required), Body (optional), and Footer (optional).
  • The Header format is <type>(<scope>): <short summary>, where type must comply with conventions (e.g., feat, fix, docs, etc.).
  • It is recommended to use git commit.template to set a global or project-level commit template to ensure team members follow a unified format.
  • Use git config --global commit.cleanup strip to automatically remove comment lines from commit messages and prevent log pollution.
  • When linking Issues or PRs, it is recommended to use keywords like Closes #123 or Fixes #123 to facilitate automated management.

Commit Format Structure ​

The Angular Commit Format divides the message into three parts, separated by blank lines.

xml
<header>
<BLANK LINE>
<body>
<BLANK LINE>
<footer>

Header Conventions ​

The Header is the only required section, following the format <type>(<scope>): <short summary>.

  • Type: Used to categorize the nature of the change. Common types include feat (new feature), fix (bug fix), docs (documentation changes), refactor (refactoring), perf (performance improvements), test (tests), build (build/dependency changes), and ci (CI configuration changes).
  • Scope: Indicates the affected module or package; can be omitted if there is no clear scope.
  • Short Summary: A concise description of the changes. It is recommended to use the imperative mood (e.g., "change" instead of "changed"), avoid capitalizing the first letter, and omit the period at the end.

Body and Footer ​

  • Body: Explains the motivation for the change and the contrast between the previous and current behavior. Can be omitted for simple changes.
  • Footer: Used to note BREAKING CHANGE or DEPRECATED information. It can also be used to link to an Issue Tracker; for example, using Closes #123 in GitHub or GitLab will automatically close the corresponding ticket upon merging.

Setting Up a Git Commit Template ​

To avoid forgetting the conventions, you can use Git's built-in template feature to unify the format.

Setup Steps ​

  1. Create a .gitmessage.txt file containing descriptions and conventions for each field.
  2. Use the following commands for global configuration:
git
git config --global commit.template ~/.gitmessage.txt
git config --global commit.cleanup strip

Configuration Explanation ​

  • commit.template: Specifies the path to the template file.
  • commit.cleanup strip: Ensures that comment lines starting with # and extra blank lines are automatically removed during a commit.

TIP

Git configuration priority is: Local (.git/config) > Global (~/.gitconfig) > System (/etc/gitconfig). If you need to set it for a specific project, omit the --global parameter.

Support in Version Control Software ​

Not all GUI tools automatically handle # comment lines; it is recommended to check your tool's settings:

  • GitKraken: Requires manually checking "Removes comments from commit messages".
  • Sourcetree: Formally supports Git Commit Templates since version 3.4.20.
  • Git Extensions: Automatically ignores comment lines starting with # by default.

Change Log ​

  • 2024-07-23 Initial document creation.
  • 2024-09-20
    • Updated support for Git Commit Template in Sourcetree 3.4.20 for Windows.
    • Corrected the description of configuration file locations.